Enterprise Deployment and Configuration

Best practices

Before proceeding with the installation and configuration of the ReversingLabs browser extension, read through the following recommendations to ensure the browser extension maintains security and compliance.

Internal document privacy

Review ReversingLabs Privacy documentation to ensure the Account Role configured for the browser extension’s download scanning function conforms to your enterprise’s privacy policy.

As a best practice, it is recommended that all files scanned by the browser extension leverage a Private Account Role. Files uploaded using a Public Account Role are available to other ReversingLabs customers.

If you are unsure which Account Role has been set up for you, contact support@reversinglabs.com.

For organizations whose main use case is ensuring files from external sources are scanned, an additional best practice is to add your organization's internal sites, such as SharePoint, document repositories, and other internal systems, to the list of excluded domains. This ensures that users can access the domains, but the extension does not scan files downloaded from those trusted, private locations.

Credential security

Developer Tools is a feature present in any modern browser, which is enabled by default and allows access to browser memory spaces. Sensitive information, such as the credentials used to access Spectra Analyze or Spectra Intelligence, can be accessed using the Developer Tools feature.

Browser Policy Page is another default feature of any modern browser, and it displays the current policies enforced for the browser, and the installed browser extensions. Sensitive information, such as the credentials used to access Spectra Analyze or Spectra Intelligence, can be accessed using the Policy Page feature.

As a best practice, ReversingLabs recommends the following:

Disable developer tools: it is strongly recommended you disable developer tools using your organization's browser management console.
Block browser policy page: explicitly block the appropriate policy page for all non-administrative users using the browser’s URLBlocklist function:
- Microsoft Edge: block edge://policy. For more information, see Microsoft Edge Browser Policy Doumentation - URLBlocklist.
- Google Chrome: block chrome://policy. For more information, see Chrome Enterprise Policy List & Management Documentation - URLBlocklist.
Use API keys: wherever possible, use API tokens instead of login credentials to access Spectra Analyze. API keys provide a more secure method of authentication, reducing the risk of credential exposure.
Create a dedicated service account: create a dedicated service account with limited permissions for the browser extension.

Blocked domains access

As a best practice, ReversingLabs recommends you include IP addresses for blocked domains in addition to the domain(s) being blocked to prevent users from attempting direct IP address access to blocked domains. For more information about configuring blocked domains, see Blocklist module.

Download scanning

The browser extension's download scanning feature has a default file size limit of 200 MB. Files larger than this cannot be automatically scanned, and if users submit such files, the scan fails. However, files of any sizes can be downloaded if the ReversingLabs browser extension doesn't attempt to scan them.

If your users frequently work with large files, it is recommended you allow downloading files without scanning by doing the following:

Disable automatic download scanning to avoid delays.
Alternatively, enable the Prompt for confirmation option. This allows users to decide whether to scan files on a case-by-case basis.

Installation

For bulk deployment and management on a large number of systems, your organization must have a configured IT environment to enforce installation and configuration of a browser and the extension.

To deploy a supported browser to all machines in your organization, and install the ReversingLabs browser extension on them, use either of the following options.

Mobile Device Management (MDM) tool: recommended installation approach for on-prem-managed machines with any supported OS.
MSI installer: alternative installation approach for on-prem networks using Active Directory and Group Policy to manage Windows machines.
Mass deployment script: alternative installation approach for on-prem-managed Linux machines.
Chrome Enterprise Core: recommended when managing a Google Chrome browser from a central cloud-based console.

info

For more information about bulk deployment using any of these options, refer to the appropriate official documentation.

Configuration

Windows configuration

When configuring Windows machines, it is recommended you use a Mobile Device Management (MDM) tool. Alternatively, use a Group Policy Object (GPO) for traditional on-prem deployments. Do the following:

In either scenario, follow official documentation for creating and configuring a registry item and key.

Configure the registry item to create a key, adding a valid extension ID:

HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Google\Chrome\3rdparty\extensions\{32_CHARACTER_RL_EXTENSION_ID}\policy

Populate the registry item with the following values, replacing placeholders with valid information. For more information, see Configuration schema details.

"configuration_credentials"="{\"managed_credentials\": <put boolean value>,\"spectra_intelligence\":{\"username\": \"<put valid username>\",\"password\":\"<put valid password>\"},\"spectra_analyze\":{\"host\":\"<put valid hostname or path>\",\"key\":\"<put valid API key>\"},\"sa_username\":\"<put valid username>\",\"sa_password\":\"<put valid password>\"}"
"general_options"="{\"highlight\":{\"domain\":{\"value\":<put boolean value>,\"optional\":<put boolean value>},\"hash\":{\"value\":<put boolean value>,\"optional\":<put boolean value>},\"ipv4\":{\"value\":<put boolean value>,\"optional\":<put boolean value>},\"url\":{\"value\":<put boolean value>,\"optional\":<put boolean value>}}}"
"safe_url_settings"="{\"active\":{\"value\":<put boolean value>,\"optional\":<put boolean value>},\"allow_risky_redirect\":{\"value\":<put boolean value>,\"optional\":<put boolean value>},\"allow_continue_when_service_unavailable\":{\"value\":<put boolean value>,\"optional\":<put boolean value>},\"allow_continue_when_quota_hit\":{\"value\":<put boolean value>,\"optional\":<put boolean value>}}"
"download_scan_settings"="{\"prompt_for_confirmation\":{\"value\":<put boolean value>,\"optional\":<put boolean value>},\"scan_downloads\":{\"value\":<put boolean value>,\"optional\":<put boolean value>},\"allow_risky_download\":{\"value\":<put boolean value>,\"optional\":<put boolean value>}}"
"support_mail"="<put email address>"
"excluded_list_locked"="<put boolean value>"
"blocklist_module"="[[\"<put string value>\"]]"
"excludelist_module"="[[\"<put string value>\"]]"
"analytics_enabled"="<put boolean value>"

Reload Google Chrome to start using the extension.

Linux configuration

Create a JSON file with the following values, replacing placeholders with valid information. For more information, see Configuration schema details.

{  
  "3rdparty": {  
    "extensions": {  
      "<32_CHARACTER_RL_EXTENSION_ID>": {  
        "policy": {  
          "configuration_credentials": {  
            "managed_credentials": "<put boolean value>",  
            "spectra_intelligence": {  
              "username": "<put valid username>",  
              "password": "<put valid password>"  
            },  
            "spectra_analyze": {  
              "host": "<put valid hostname or path>",  
              "key": "<put valid API key>"  
            },  
            "sa_username": "<put valid username>",  
            "sa_password": "<put valid password>"  
          },  
          "general_options": {  
            "highlight": {  
              "domain": {  
                "value": "<put boolean value>",  
                "optional": "<put boolean value>"  
              },  
              "hash": {  
                "value": "<put boolean value>",  
                "optional": "<put boolean value>"  
              },  
              "ipv4": {  
                "value": "<put boolean value>",  
                "optional": "<put boolean value>"  
              },  
              "url": {  
                "value": "<put boolean value>",  
                "optional": "<put boolean value>"  
              }  
            }  
          },  
          "safe_url_settings": {  
            "active": {  
              "value": "<put boolean value>",  
              "optional": "<put boolean value>"  
            },  
            "allow_risky_redirect": {  
              "value": "<put boolean value>",  
              "optional": "<put boolean value>"  
            },  
            "allow_continue_when_service_unavailable": {  
              "value": "<put boolean value>",  
              "optional": "<put boolean value>"  
            },  
            "allow_continue_when_quota_hit": {  
              "value": "<put boolean value>",  
              "optional": "<put boolean value>"  
            }  
          },  
          "download_scan_settings": {  
            "prompt_for_confirmation": {  
              "value": "<put boolean value>",  
              "optional": "<put boolean value>"  
            },  
            "scan_downloads": {  
              "value": "<put boolean value>",  
              "optional": "<put boolean value>"  
            },  
            "allow_risky_download": {  
              "value": "<put boolean value>",  
              "optional": "<put boolean value>"  
            }  
          },  
          "support_mail": "<put email address>",  
          "excluded_list_locked": "<put boolean value>",  
          "blocklist_module": [  
            [  
              "<put string value>"  
            ]  
          ],  
          "excludelist_module": [  
            [  
              "<put string value>"  
            ]  
          ],  
          "analytics_enabled": "<put boolean value>"  
        }  
      }  
    }  
  }  
} 

If it doesn't already exist, create a directory with the following path on managed machines: /etc/opt/chrome/policies/managed/.
Push your JSON file to that directory.
Reload Google Chrome to start using the extension.

macOS configuration

Configure the property list created during installation by doing the following:

Populate the .plist file with the following values, replacing placeholders with valid information. For more information, see Configuration schema details.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>com.google.Chrome.3rdparty.extensions.&lt;32_CHARACTER_RL_EXTENSION_ID&gt;</key>
  <dict>
    <key>state</key>
    <string>always</string>
    <key>value</key>
    <dict>
      <key>policy</key>
      <dict>
        <key>configuration_credentials</key>
        <dict>
          <key>managed_credentials</key>
          <true/>
          <key>spectra_intelligence</key>
          <dict>
            <key>username</key>
            <string>&lt;put valid username&gt;</string>
            <key>password</key>
            <string>&lt;put valid password&gt;</string>
          </dict>
          <key>spectra_analyze</key>
          <dict>
            <key>host</key>
            <string>&lt;put valid hostname or path&gt;</string>
            <key>key</key>
            <string>&lt;put valid API key&gt;</string>
          </dict>
          <key>sa_username</key>
          <string>&lt;put valid username&gt;</string>
          <key>sa_password</key>
          <string>&lt;put valid password&gt;</string>
        </dict>
        <key>general_options</key>
        <dict>
          <key>highlight</key>
          <dict>
            <key>domain</key>
            <dict>
              <key>value</key>
              <true/>
              <key>optional</key>
              <true/>
            </dict>
            <key>hash</key>
            <dict>
              <key>value</key>
              <true/>
              <key>optional</key>
              <true/>
            </dict>
            <key>ipv4</key>
            <dict>
              <key>value</key>
              <false/>
              <key>optional</key>
              <false/>
            </dict>
            <key>url</key>
            <dict>
              <key>value</key>
              <true/>
              <key>optional</key>
              <true/>
            </dict>
          </dict>
        </dict>
        <key>safe_url_settings</key>
        <dict>
          <key>active</key>
          <dict>
            <key>value</key>
            <true/>
            <key>optional</key>
            <true/>
          </dict>
          <key>allow_risky_redirect</key>
          <dict>
            <key>value</key>
            <false/>
            <key>optional</key>
            <false/>
          </dict>
          <key>allow_continue_when_service_unavailable</key>
          <dict>
            <key>value</key>
            <false/>
            <key>optional</key>
            <false/>
          </dict>
          <key>allow_continue_when_quota_hit</key>
          <dict>
            <key>value</key>
            <false/>
            <key>optional</key>
            <false/>
          </dict>
        </dict>
        <key>download_scan_settings</key>
        <dict>
          <key>prompt_for_confirmation</key>
          <dict>
            <key>value</key>
            <false/>
            <key>optional</key>
            <false/>
          </dict>
          <key>scan_downloads</key>
          <dict>
            <key>value</key>
            <false/>
            <key>optional</key>
            <false/>
          </dict>
          <key>allow_risky_download</key>
          <dict>
            <key>value</key>
            <false/>
            <key>optional</key>
            <false/>
          </dict>
        </dict>
        <key>support_mail</key>
        <string>&lt;put email address&gt;</string>
        <key>excluded_list_locked</key>
        <false/>
        <key>blocklist_module</key>
        <array>
          <array>
            <string>&lt;put string value&gt;</string>
          </array>
        </array>
        <key>excludelist_module</key>
        <array>
          <array>
            <string>&lt;put string value&gt;</string>
          </array>
        </array>
        <key>analytics_enabled</key>
        <false/>
      </dict>
    </dict>
  </dict>
</dict>
</plist>

Apply this policy to managed macOS machines.
Reload Google Chrome to start using the extension.

Testing the extension

To test if the extension has been successfully configured on managed machines, do the following:

On a managed machine, open Google Chrome.
Go to chrome://policy and check if the policy page displays the name of your managed extension alongside information for all managed variables.
- If you don't see the extension on this page, check if you have used the correct 32 character extension ID by going to chrome://extensions and inspecting the extension ID.
To check if your managed values have been set up correctly, press F12 to open Inspect, and go to Application > Storage > Extension storage > Managed.

Configuration options

You can customize how the extension identifies and interacts with Indicators of Compromise (IOCs), file downloads and URL reputation checks.

The following features are available:

Indicator highlighting: URLs, Domains, IPv4 addresses, and Hashes are automatically identified on web pages and indicated with a RL icon.
Scan downloads: downloaded files are automatically scanned using Spectra Analyze or Spectra Intelligence.
Prompt when downloading files: the extension asks for confirmation before a file is submitted for analysis which provides more control over uploads for analysis.
Scan URLs: the extension checks URLs before opening them. If a URL is flagged as suspicious or malicious, the browser redirects you to a warning page before proceeding.

User permissions

When deploying the extension in enterprise mode, an IT administrator should control which options are enabled or disabled by default, and if users are allowed to switch options on or off.

Configuration schema details

This section explains how to configure all options through centralized management when using the extension in enterprise mode. All information below is applicable to Windows, Linux and macOS configuration. If needed, you can also customize and distribute different configurations to specific groups.

By default, all options are disabled and all credentials are empty. This is a failsafe to ensure that if the IT administrator's configuration is incorrect or incomplete, the extension starts in a non-functional state rather than causing errors or unexpected behavior.

For options set as optional: true, the IT administrator sets their initial value; however, users can change the value. Their preference is then saved and used instead of the administrator's setting. To avoid this, set optional to false.

Credential and management settings

Credential and management settings are set up under configuration_credentials.

These settings control the extension's authentication for Spectra Analyze and Spectra Intelligence services, and they determine whether enterprise users can change their own settings.

Authentication mechanism fallback

In enterprise mode, in case one authentication mechanism fails, it falls back to the next in line in the authentication priority chain.

Authentication chain from highest to lowest priority: Spectra Analyze credentials > Spectra Analyze API key > Spectra Intelligence credentials.

When there is no next in line, the user is disabled.

managed_credentials: boolean; global setting which determines if users can locally override the configuration in their own browser.
- true: users can't override the configuration.
- false: users can override the configuration.
spectra_intelligence: contains the credentials to connect to Spectra Intelligence.
- username: username for the Spectra Intelligence account.
- password: password for the Spectra Intelligence account.
spectra_analyze: contains the credentials to connect to Spectra Analyze.
- host: hostname or IP address of the Spectra Analyze appliance.
- key: API key required for authentication with the Spectra Analyze appliance.
Best practices
For more information about best practices when setting up credentials, see Credential security.
sa_username: separate credentials if you want to configure users based on their username and password in Spectra Analyze.
sa_password: separate credentials if you want to configure users based on their username and password in Spectra Analyze.

General highlighting options

General highlighting options are set up under general_options.

These settings control the automatic highlighting of Indicators of Compromise (IoCs) on web pages.

highlight: container for all IoC highlighting rules.
- domain: rule for highlighting domain names.
- hash: rule for highlighting file hashes.
- ipv4: rule for highlighting IPv4 addresses.
- url: rule for highlighting URLs.

For each IoC type listed above, you can set its default state and whether users can change it.

value: boolean; enables or disables the highlighting for that specific IoC type.
optional: boolean; determines if the user can change this setting.

Safe URL settings

info

Safe URL settings constitute allowing users risky redirects, and allowing them to continue when service is unavailable and when quota is hit. These options can only be set up by an IT administrator in enterprise mode.

The safe URL feature is set up under safe_url_settings. These settings inspect links before a user can visit them.

active: global setting which determines if the safe URL feature is enabled.
- value: boolean; enables or disables the safe URL feature.
- optional: boolean; determines if the user can change this setting.
allow_risky_redirect: decides if a user can proceed to a URL flagged as malicious or suspicious.
- value: boolean; enables or disables the user from continuing.
- optional: boolean; determines if the user can change this setting.
allow_continue_when_service_unavailable: decides if a user can proceed when the safe URL analysis service cannot be reached, for example, if the Spectra Analyze service is down.
- value: boolean; enables or disables the user from continuing.
- optional: boolean; determines if the user can change this setting.
allow_continue_when_quota_hit: decides if a user can proceed when the analysis service has reached its usage limit.
- value: boolean; enables or disables the user from continuing.
- optional: boolean; determines if the user can change this setting.

Download scan settings

Download scanning is set up under download_scan_settings. These settings control the feature that automatically scans file downloads for threats.

prompt_for_confirmation: controls whether to ask the user before starting a file scan. The user can also choose to bypass the scan and directly download a file without checking its classification.

warning
If prompt_for_confirmation has value: true, the user can download potentially malicious files by directly downloading without scanning.
- value: boolean; enables or disables a confirmation prompt.
- optional: boolean; determines if the user can change this setting.
scan_downloads: global setting which determines if the automatic scanning of downloads is enabled.
- value: boolean; enables or disables the automatic scanning of downloads.
- optional: boolean; determines if the user can change this setting.
allow_risky_download: controls if a user can keep a file that has been flagged as risky. Risky files include malicious and suspicious files, and files that have not been scanned. For more information, see prompt_for_confirmation.
- value: boolean; if true, the user can choose to download the risky file; if false, the download is blocked.
- optional: boolean; determines if the user can change this setting.

Support email

Support email is set up under support_mail. IT administrators can enter a target mail where enterprise users can send their enquiries.

support_email: email address for user support.

Excluded list access

Whether or not users can update the list of excluded domains is set up under excluded_list_locked.

Excluded domains are domains that users can visit, but the ReversingLabs browser extension doesn't work on them.

excluded_list_locked: boolean; determines if the user can update the list of excluded domains.

Blocklist module

The list of blocked domains is set up under blocklist_module. If a hostname matches one of the entries, files cannot be downloaded and the user is blocked from visiting the site.

Blocked domains are domains that users can't visit. Users can't remove domains from this list, but they can add domains to it.

The blocklist element is an array with the following values:

"s": must be set to "s" so that it identifies this as a simple element.
"^example\.com$": regex used for hostname-matching.
- [0-9a-zA-Z-]+: wildcard that represents a single level in a domain name. In the UI, the wildcard is shown as an asterisk (*).
"i": regex flag; only "i" is currently supported, making the pattern search case-insensitive.

Sample configuration:

"blocklist_module": [
  [
    "s",
    "^blocked-domain\\.com$",
    "i"
  ],
  [
    "s",
    "^[0-9a-zA-Z-]+\\.another-blocked-domain\\.com$",
    "i"
  ]
]

Best practices

For more information about best practices when setting up this module, see Blocked domains access.

Excludelist module

The list of excluded domains is set up under excludelist_module. If a hostname matches one of the entries, file downloads are not intercepted and the user is allowed to visit the site without checking its URL reputation.

Excluded domains are domains that users can visit, but the ReversingLabs browser extension doesn't work on them.

Best practices

For more information about best practices when setting up this module, see Internal document privacy.

The excludelist element is an array with the following values:

"s": must be set to "s" so that it identifies this as a simple element.
"^example\.com$": regex used for hostname-matching.
- [0-9a-zA-Z-]+: wildcard that represents a single level in a domain name. In the UI, the wildcard is shown as an asterisk (*).
"i": regex flag; only "i" is currently supported, making the pattern search case-insensitive.

Sample configuration:

"excludelist_module": [
  [
    "s",
    "^allowed-domain\\.com$",
    "i"
  ],
  [
    "s",
    "^[0-9a-zA-Z-]+\\.another-allowed-domain\\.com$",
    "i"
  ]
]

Analytics

To control whether enterprise users can send analytics data or not, set analytics_enabled to either true or false.

Error report buttons

The extension uses mailto: links to allow users to report any issues encountered while using the extension. To use this feature, users must have a default email app set up.

Windows email app setup

Click Start and go to Settings > Apps > Default apps.
On the Default apps page, do one of the following:
- Windows 10
  1. Go to Email.
  2. Select the current app listed.
  3. Under Choose an app, select your desired client.
- Windows 11
  1. Go to Set defaults for applications.
  2. Scroll to find your desired client, then select it.
  3. Set the default mail client for a specific file type:
    1. Select an item.
    2. Select your desired client.
    3. Select Set default to confirm.

Linux email app setup

How mailto:// is handled depends on the distribution and desktop environment. Check your distribution's documentation on how to set up the URL handler.

macOS email app setup

Open the Apple Mail app.
From the menu bar, click Mail and select Preferences.
Go to General > Default email reader, and select an email app from the dropdown menu.
1. If you use webmail, select your preferred browser from the dropdown menu.
2. Check if your preferred browser has any additional settings which need to be altered.

Troubleshooting

Spectra Analyze self-signed certificates

Issues with the TLS certificate setup present as network connection issues in the extension. This affects the following Spectra Analyze instances:

Self-hosted instances
Instances deployed with self-signed certificates

By default, the extension requires that any host configured with the https:// protocol provides a valid and trusted certificate. To resolve this issue, make sure that the certificate from your Spectra Analyze instance is trusted by your OS and by your browser.

warning

Before proceeding, confirm the authenticity of the certificate which will be added to the trust store.

info

If the certificate’s Common Name does not match the Spectra Analyze instance DNS, the error persists even for trusted certificates.

Follow one of these steps to add the certificate to your trust store:

Add the certificate to the OS trust store.
1. Follow your operating system vendor’s instructions for adding trusted certificates.
2. Clear the browser cache and restart the browser.
3. Open chrome://certificate-manager/localcerts/platformcerts and confirm that the browser has detected the added certificate.
Add the certificate to Chrome’s imported certificates.
1. Open chrome://certificate-manager/localcerts/usercerts in your browser.
2. Use the Import button to add the certificate.

After these steps are completed, the connection can be configured.

Best practices​

Internal document privacy​

Credential security​

Blocked domains access​

Download scanning​

Installation​

Configuration​

Windows configuration​

Linux configuration​

macOS configuration​

Testing the extension​

Configuration options​

Configuration schema details​

Credential and management settings​

General highlighting options​

Safe URL settings​

Download scan settings​

Support email​

Excluded list access​

Blocklist module​

Excludelist module​

Analytics​

Error report buttons​

Windows email app setup​

Linux email app setup​

macOS email app setup​

Troubleshooting​

Spectra Analyze self-signed certificates​

Best practices

Internal document privacy

Credential security

Blocked domains access

Download scanning

Installation

Configuration

Windows configuration

Linux configuration

macOS configuration

Testing the extension

Configuration options

Configuration schema details

Credential and management settings

General highlighting options

Safe URL settings

Download scan settings

Support email

Excluded list access

Blocklist module

Excludelist module

Analytics

Error report buttons

Windows email app setup

Linux email app setup

macOS email app setup

Troubleshooting

Spectra Analyze self-signed certificates